build: port calendaring-jmap's uv, Makefile and docs setup - #48

Documentation build overview

📚 calendaring-sync | 🛠️ Build #35810944 | 📁 Comparing e5c0ece against latest (1bb9ad2)

  🔍 Preview build  

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

@stevepiercy just tagging you for context, no need to review this one. I ported the calendaring-jmap setup over to calendaring-sync, and it turned into a bit of a journey.

It started on my Windows machine, where none of the make targets would run. The .venv/bin/... paths come out empty there, so make html ended up running "" as the command. I switched everything to uv run, which finds the environment on any platform.

Then I tested linkcheckbroken by putting a broken link on a page on purpose, and the target still passed. Two things were going on. Only grep's exit status counts, so even a crashed sphinx-build passes. And on Windows, sphinx-build colors its output even into a pipe, so grep never matched "broken" anyway. Reading PIPESTATUS and passing --no-color sorted both.

Vale had a quieter one. The TokenIgnores pattern uses .+, so on a line with two roles it skips everything from the first role to the last backtick, prose included. When I changed it to [^\x60]+, three alerts showed up here that had been hidden all along.

A couple more while I was reading the config. The lint job runs make format, which fixes files instead of checking them, so it can never fail. The Read the Docs skip list starts with ., which matches every file, so the skip never actually kicks in. And Jinja drops a template's last newline, so the apidoc templates need a trailing blank line, and then end-of-file-fixer has to leave them alone.

I'll send the same fixes to calendaring-jmap in a PR, and would love your review there.